PATHMac OS 8 Developer Documentation > Human Interface Toolbox > Menu Manager >

Mac OS 8 Menu Manager Reference

Manipulating and Accessing Menu Item Characteristics

The following Menu Manager functions for manipulating and accessing menu item characteristics are new, changed, or not recommended with Appearance Manager 1.0:


SetItemCmd

Sets the value of the keyboard equivalent field of a menu item. When the Appearance Manager is available, you should call SetMenuItemModifiers , SetMenuItemHierarchicalID , and SetMenuItemTextEncoding instead of SetItemCmd to set a menu item's keyboard equivalent and text encoding and to indicate that a menu item has a submenu.


VERSION NOTES

Not recommended with Appearance Manager 1.0 and later.


SetMenuItemCommandID

Sets a menu item's command ID.

pascal OSErr SetMenuItemCommandID (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     UInt32 inCommandID);
inMenu
A handle to the menu that contains the menu item for which you wish to set a command ID.
inItem
An integer representing the item number of the menu item.
inCommandID
An integer representing the command ID that you wish to set.
function result
A result code; see Result Codes .

DISCUSSION

You can use a menu item's command ID as a position-independent method of signalling a specific action in an application.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

GetMenuItemCommandID .


GetMenuItemCommandID

Obtains a menu item's command ID.

pascal OSErr GetMenuItemCommandID (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     UInt32* outCommandID);
inMenu
A handle to the menu that contains the menu item for which you wish to get a command ID.
inItem
An integer representing the item number of the menu item.
outCommandID
Pass a pointer to an unsigned 32-bit integer value. On return, the value is set to the item's command ID.
function result
A result code; see Result Codes .

DISCUSSION

After a successful call to MenuSelect , MenuEvent , or MenuKey , call the GetMenuItemCommandID function to get a menu item's command ID. You can use a menu item's command ID as a position-independent method of signalling a specific action in an application.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

SetMenuItemCommandID .


SetMenuItemFontID

Sets the font for a menu item.

pascal OSErr SetMenuItemFontID (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     SInt16 inFontID);
inMenu
A handle to the menu that contains the menu item for which you wish to set the font.
inItem
An integer representing the item number of the menu item.
inFontID
An integer representing the font ID that you wish to set.
function result
A result code; see Result Codes .

DISCUSSION

The SetMenuItemFontID function enables you to set up a font menu with each item being drawn in the actual font.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

GetMenuItemFontID .


GetMenuItemFontID

Obtains a menu item's font ID.

pascal OSErr GetMenuItemFontID (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     SInt16* outFontID);
inMenu
A handle to the menu that contains the menu item for which you wish to get a font ID.
inItem
An integer representing the item number of the menu item.
outFontID
Pass a pointer to a signed 16-bit integer value. On return, the value is set to the font ID for the menu item.
function result
A result code; see Result Codes .

VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

SetMenuItemFontID .


SetMenuItemHierarchicalID

Attaches a submenu to a menu item.

pascal OSErr SetMenuItemHierarchicalID (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     SInt16 inHierID)
inMenu
A handle to the menu that contains the menu item to which you wish to attach a submenu.
inItem
An integer representing the item number of the menu item.
inHierID
An integer representing the menu ID of the submenu you wish to attach. This menu should be inserted into the menu list by calling InsertMenu .
function result
A result code; see Result Codes .

DISCUSSION

The SetMenuItemHierarchicalID function should be called instead of setting the keyboard equivalent to 0x1B. When the Appearance Manager is available, you should call SetMenuItemHierarchicalID instead of SetItemMark to set the menu ID of a menu item's submenu. However, you can still use SetItemMark to set the mark of a menu item.


VERSION NOTES

Available with Appearance Manager 1.0 and later.

Setting a submenu with an menu ID greater than 255 is only supported under Mac OS 8.5 and later.


GetMenuItemHierarchicalID

Obtains the menu ID of a specified submenu.

pascal OSErr GetMenuItemHierarchicalID (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     SInt16 *outHierID)
inMenu
A handle to the menu that contains the menu item for which you wish to get the submenu's menu ID.
inItem
An integer representing the item number of the menu item.
outHierID
Pass a pointer to a signed 16-bit integer value. On return, the value is set to the menu ID of the submenu.
function result
A result code; see Result Codes .

VERSION NOTES

Available with Appearance Manager 1.0 and later.


SetMenuItemIconHandle

Sets a menu item's icon.

pascal OSErr SetMenuItemIconHandle (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     UInt8 inIconType,
                     Handle inIconHandle);
inMenu
A handle to the menu that contains the menu item for which you wish to set an icon.
inItem
An integer representing the item number of the menu item.
inIconType
Pass a value representing the type of icon ( 'ICON' , 'cicn' , 'SICN' , icon suite, or IconRef ) you wish to attach; see Menu Item Icon Type Constants for descriptions of possible values.
inIconHandle
Pass a handle to the icon you wish to attach to a menu item.
function result
A result code; see Result Codes .

DISCUSSION

The SetMenuItemIconHandle function sets the icon of a menu item with an icon handle instead of a resource ID. SetMenuItemIconHandle allows you to set icons of type 'ICON' , 'cicn' , 'SICN' , as well as icon suites. To set resource-based icons for a menu item, call SetItemIcon .

WARNING

Disposing of the menu will not dispose of the icon handles set by this function. To prevent memory leaks, your application should dispose of the icons when you dispose of the menu.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

GetMenuItemIconHandle .


GetMenuItemIconHandle

Obtains a handle to a menu item's icon.

pascal OSErr GetMenuItemIconHandle (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     UInt8* outIconType,
                     Handle* outIconHandle);
inMenu
A handle to the menu that contains the menu item for which you wish to obtain the handle.
inItem
An integer representing the item number of the menu item.
outIconType
Pass a pointer to an unsigned 8-bit value. On return, the value specifies the type of icon ( 'ICON' , 'cicn' , 'SICN' , icon suite, or IconRef ) for which you are obtaining a handle. If the menu item has no icon attached, this parameter will contain kMenuNoIcon . See Menu Item Icon Type Constants for descriptions of possible values.
outIconHandle
Pass a pointer to a handle. On return, outIconHandle contains a handle to the icon that is attached to the menu item. If the menu item has no icon attached, this parameter contains nil .
function result
A result code; see Result Codes .

DISCUSSION

The GetMenuItemIconHandle function gets the icon handle and type of icon of the specified menu item. If you wish to get a resource-based menu item icon, call GetItemIcon .


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

SetMenuItemIconHandle .


SetMenuItemKeyGlyph

Substitutes a keyboard glyph for the glyph normally displayed for a menu item's keyboard equivalent.

pascal OSErr SetMenuItemKeyGlyph (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     SInt16 inGlyph)
inMenu
A handle to the menu that contains the menu item for which you wish to substitute a keyboard glyph.
inItem
An integer representing the item number of the menu item.
inGlyph
An integer representing the substitute glyph to display. Pass 0 if you wish no substitution to occur. For a description of keyboard glyphs and a list of the keyboard font character codes, see 'xmnu' .
function result
A result code; see Result Codes .

DISCUSSION

The SetMenuItemKeyGlyph function overrides the character that would normally be displayed in a menu item's keyboard equivalent with a substitute keyboard glyph. This is useful if the keyboard glyph in the font doesn't match the actual character generated. For example, you might use this function to display function keys.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

GetMenuItemKeyGlyph .


GetMenuItemKeyGlyph

Obtains the keyboard glyph for a menu item's keyboard equivalent.

pascal OSErr GetMenuItemKeyGlyph (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     SInt16 *outGlyph)
inMenu
A handle to the menu that contains the menu item for which you wish to get the keyboard glyph.
inItem
An integer representing the item number of the menu item.
outGlyph
A pointer to a signed 16-bit integer value. On return the value is set to the modifier key glyph. For a description of keyboard glyphs and a list of the keyboard font character codes, see 'xmnu' .
function result
A result code; see Result Codes .

VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

SetMenuItemIconHandle .


SetMenuItemModifiers

Sets the modifier key(s) that must be pressed with a character key to select a particular menu item.

pascal OSErr SetMenuItemModifiers (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     UInt8 inModifiers);
inMenu
A handle to the menu that contains the menu item for which you wish to set the modifier key(s).
inItem
An integer representing the item number of the menu item.
inModifiers
A value representing the modifier key(s) to be used in selecting the menu item; see Modifier Key Mask Constants .
function result
A result code; see Result Codes .

DISCUSSION

You can call the SetMenuItemModifiers function to change the modifier key(s) you can include with a character key to create your keyboard equivalent. For example, you can change Command- x to Command-Option-Shift- x . By default, the Command key is always specified; however, you can remove the Command key by setting the kMenuNoCommand flag in the modifier keys field of an extended menu item entry in the 'xmnu' resource; see 'xmnu' .


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

GetMenuItemModifiers .


GetMenuItemModifiers

Obtains the modifier keys that must be pressed with a character key to select a particular menu item.

pascal OSErr GetMenuItemModifiers (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     UInt8* outModifiers);
inMenu
A handle to the menu that contains the menu item for which you wish to get the modifier key(s).
inItem
An integer representing the item number of the menu item.
outModifiers
A pointer to an unsigned 8-bit value. On return, the bits of the value are set to indicate the modifier keys that can be used in selecting the menu item; see Modifier Key Mask Constants .
function result
A result code; see Result Codes .

VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

SetMenuItemModifiers .


SetMenuItemRefCon

Sets application-specific information for a menu item.

pascal OSErr SetMenuItemRefCon (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     UInt32 inRefCon);
inMenu
A handle to the menu that contains the menu item with which you wish to associate information.
inItem
An integer representing the item number of the menu item.
inRefCon
An unsigned 32-bit integer value. Pass a reference constant to associate with the menu item.
function result
A result code; see Result Codes .

DISCUSSION

If you have any data you want to associate with a menu item, you can do so using the SetMenuItemRefCon function.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

GetMenuItemRefCon .


GetMenuItemRefCon

Obtains application-specific information for a menu item.

pascal OSErr GetMenuItemRefCon (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     UInt32* outRefCon);
inMenu
A handle to the menu that contains the menu item for which you wish to get information.
inItem
An integer representing the item number of the menu item.
outRefCon
A pointer to an unsigned 32-bit integer value. On return, the value is set to the reference constant associated with the menu item.
function result
A result code; see Result Codes .

DISCUSSION

If you have assigned any data to a menu item using SetMenuItemRefCon function, you can read it using the GetMenuItemRefCon function.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

SetMenuItemRefCon .


SetMenuItemRefCon2

Sets additional application-specific information for a menu item.

pascal OSErr SetMenuItemRefCon2 (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     UInt32 inRefCon);
inMenu
A handle to the menu that contains the menu item for which you wish to set information.
inItem
An integer representing the item number of the menu item.
inRefCon
An unsigned 32-bit integer value. Pass a reference constant to associate with the menu item.
function result
A result code; see Result Codes .

DISCUSSION

If you have data you want to associate with a menu item in addition to that set with the SetMenuItemRefCon function, you can do so using the SetMenuItemRefCon2 function.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

GetMenuItemRefCon2 .


GetMenuItemRefCon2

Obtains application-specific information for a menu item.

pascal OSErr GetMenuItemRefCon2 (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     UInt32* outRefCon);
inMenu
A handle to the menu that contains the menu item for which you wish to retrieve information.
inItem
An integer representing the item number of the menu item.
outRefCon
A pointer to an unsigned 32-bit integer value. On return, the value is set to the reference constant associated with the menu item.
function result
A result code; see Result Codes .

DISCUSSION

If you have assigned any data to a given menu item using SetMenuItemRefCon2 function, you can read it using the GetMenuItemRefCon function.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

SetMenuItemRefCon2 .


SetMenuItemTextEncoding

Sets the text encoding for a menu item's text.

pascal OSErr SetMenuItemTextEncoding (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     TextEncoding inScriptID);
inMenu
A handle to the menu that contains the menu item whose text encoding you wish to set.
inItem
An integer representing the item number of the menu item.
inScriptID
The script code that corresponds to the text encoding you wish to set.
function result
A result code; see Result Codes .

DISCUSSION

To set the text encoding for a menu item's text, call the SetMenuItemTextEncoding function instead of SetItemCmd . If a menu item has a command code of 0x1C when SetMenuItemTextEncoding is called, the values in the command and icon fields of the menu resource are cleared and replaced with the value in the inScriptID parameter of SetMenuItemTextEncoding .


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

GetMenuItemTextEncoding .


GetMenuItemTextEncoding

Obtains the text encoding used for a menu item's text.

pascal OSErr GetMenuItemTextEncoding (
                     MenuHandle inMenu,
                     SInt16 inItem,
                     TextEncoding* outScriptID);
inMenu
A handle to the menu that contains the menu item whose text encoding you wish to get.
inItem
An integer representing the item number of the menu item.
outScriptID
A pointer to a TextEncoding value. On return, the value is set to the script code of the text encoding used in the menu item's text.
function result
A result code; see Result Codes .

DISCUSSION

If a menu item has a command code of 0x1C when GetMenuItemTextEncoding is called, GetMenuItemTextEncoding gets the value in the icon field of the menu item's menu resource.


VERSION NOTES

Available with Appearance Manager 1.0 and later.


SEE ALSO

SetMenuItemTextEncoding .

© 1998 Apple Computer, Inc. - (Last Updated 19 Nov 98)